This tech note discusses the how and why of debugging Code Fragment Manager (CFM) Libraries . Most OpenDoc parts are CFM Libraries, but I put it in the title to catch your attention. As of this writing The Debugger does not handle CFM 68K Libraries, and when possible you should debug native versions of the CFM Libraries or OpenDoc parts you are building.
Background
As you know, The Debugger lurks in the background and looks for the loading of interesting objects, such as executable resources and Applications. To do this, it patches the various flavors of the _GetResource trap and _LoadSeg. In the case of objects loaded by CFM, it installs a ‘notify’ proc which is called by CFM when Libraries are loaded, unloaded, etc. This enables The Debugger to monitor what is happening and load the appropriate ‘sym’ files just after a library is loaded.
NOTE: when I say ‘sym’ file I am referring to a file containing symbol info for a program that is formatted according to an Apple specification. Files containing information for 68K programs are suffixed with ‘.sym’ and those for PowerPC programs are suffixed with ‘.xSYM’.
In the case of 68K Applications, TD looks for a ‘sym’ file with the name AppName.sym
and PPC, ‘AppName.xsym’. To debug 68K resources, one names the ‘sym’ file as:
‘RsrcFileName/rrrr_nnn.sym’ where rrrr is the resource type (case sensitive) and nnn is the resource id in hex with no leading zeros.
For CFM libraries, the basic convention is that TD looks for the symbol info in a file named ‘LibraryName.xSYM’ in the same folder as the Library.
In addition, when an Application or Library is loaded, TD also looks at all the other CFM Libraries that are Linked in (in the ‘closure’), and if they have ‘sym’ files, then they are also loaded. If the flag DBG_SLM is OFF, then TD will NOT look for the ‘sym’ files of disk based libraries.
To debug native (Accelerated) code resources, the flag: DBG_RSRCs must be ON
and the ‘sym’ or Aux file name is ‘LibraryName.xSYM’. You may also have to set the
‘=Generic’ resource type if the resource type you are loading is not one of the standard
types I recognize
Note: The name of a library is dynamically assigned by CFM when the library is loaded.
The Library name is passed as the 3rd argument to GetDiskFragment or GetMemFragment.
This has confused many of you in the past. If you don’t give the Library a name, then
it will show up as <-> in the list of loaded libraries.
Facilities
There are a variety of ways in which you can associate a ‘sym’ file with a loaded CFM library.
Manual
You can use the Target Library command in the Tables Menu. The first time you bring it up, it will display the list of loaded libraries and ask you to select a Library. After you have hilited a library name, select the command a second time and it will put up a SF Getfile dialog and you are expected to select the ‘.xSYM’ file.
Remember that the reason it shows you the whole list of libraries, is that when you select one, you are also selecting the ‘data section’ associated with that invocation of the library.
Semi-Automatic
You can automate the above process by hiliting (.dsi file) lines of the form:
=L
LibraryName (case Sensitive)
path:Filename.xSYM
and doing a Ω-F (Execute Selection) command.
You may NOT execute such lines as part of a ‘.dsi’ file associated with an Application, ...
as it will cause recursive re-entry to the ‘add task’ processor in The Debugger.
An example of adding the symbol info for 2 libraries is:
(=L
Lib_A
myDisk: .... :Lib_A.xSYM
=L
Lib_B
myDisk: .... :Lib_B.xSYM)
One can hilite the lines by clicking on the opening paren and Ω-F
Automatic
If DBG_SLM is ON, then TD will automatically look for and process the ‘sym’ info of libraries as they are loaded. If you are debugging native code resources, then you will also have to turn the DBG_RSRCs flag on, and possibly set the =Generic Code resource type to that of the resource holding the accelerated resource. In both cases, the sym file name is ‘Libname.xSYM’.
Some Strategies
Some of you who are debugging Applications or such with a large number of associated libraries have complained to me about the amount of time it takes to load the symbol info for the libraries. Some alternatives are:
1) Rename the ‘sym’ files of the libraries you are not interested in debugging so that TD
doesn’t pick them up automatically. If you need them, use the next strategy.
2) Turn DBG_SLM OFF and load the ‘sym’ info for the libraries as you need them (after a crash, …) via the ‘semi-automatic’ method.
Remember to execute a ‘stack crawl’ command after you load the libraries.
